# -*- coding: utf-8 -*-
# @Time    : 2024/7/12 15:35
# @Author  : yujiahao
# @File    : 22_fastapi_path_conf.py
# @description:路径操作配置
from typing import Union, Set

from fastapi import FastAPI, status
from pydantic import BaseModel

# todo 路径操作装饰器支持多种配置参数。
# 这里说的参数是直接传递给路径操作装饰器，不能直接传递给路径操作函数
# 通过传递参数给路径操作装饰器 ，即可轻松地配置路径操作、添加元数据。


# todo 状态码


app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()


@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
    return item


# todo tags 参数

# tags 参数的值是由 str 组成的 list （一般只有一个 str ），tags 用于为路径操作添加标签

@app.post("/items_1/", response_model=Item, tags=["items"])
async def create_item_1(item: Item):
    return item


@app.get("/items_2/", tags=["items"])
async def read_items_2():
    return [{"name": "Foo", "price": 42}]


@app.get("/users/", tags=["users这个标签就是凿API文档这个路由前面介绍的"])
async def read_users():
    return [{"username": "johndoe"}]


# todo summary 和 description 参数
class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()


@app.post(
    "/items_3/",
    response_model=Item,
    summary="我是一个简要的说明",
    description="我是一个详细的说明",
    tags=["我也可以是一个标题,就得是列表，不能是字符串，不然会按照字符串遍历命名len(str)个", "同样的API，我是单独的标题"],
    # todo 响应描述
    response_description="response_description 只用于描述响应，description 一般则用于描述路径操作。"
)
async def create_item(item: Item):
    # todo 文档字符串（docstring）

    '''
    就是多行注释，我是一个文档注释，我会在api文档中有说明
    同时我还支持 Markdown，能正确解析和显示 Markdown 的内容，但要注意文档字符串的缩进。

    OpenAPI 规定每个路径操作都要有响应描述。

    如果没有定义响应描述，FastAPI 则自动生成内容为 "Successful response" 的响应描述
    '''
    return item


# todo 弃用路径操作
# deprecated 参数可以把路径操作标记为弃用，无需直接删除

@app.get("/items_6/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]


@app.get("/users_1/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]


@app.get("/elements/", tags=["items"], deprecated=True)
async def read_elements():
    return [{"item_id": "Foo"}]
